home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / sspsvx.z / sspsvx
Encoding:
Text File  |  2002-10-03  |  10.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SSPSVX - use the diagonal pivoting factorization A = U*D*U**T or A =
  10.      L*D*L**T to compute the solution to a real system of linear equations A *
  11.      X = B, where A is an N-by-N symmetric matrix stored in packed format and
  12.      X and B are N-by-NRHS matrices
  13.  
  14. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.      SUBROUTINE SSPSVX( FACT, UPLO, N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX,
  16.                         RCOND, FERR, BERR, WORK, IWORK, INFO )
  17.  
  18.          CHARACTER      FACT, UPLO
  19.  
  20.          INTEGER        INFO, LDB, LDX, N, NRHS
  21.  
  22.          REAL           RCOND
  23.  
  24.          INTEGER        IPIV( * ), IWORK( * )
  25.  
  26.          REAL           AFP( * ), AP( * ), B( LDB, * ), BERR( * ), FERR( * ),
  27.                         WORK( * ), X( LDX, * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      SSPSVX uses the diagonal pivoting factorization A = U*D*U**T or A =
  44.      L*D*L**T to compute the solution to a real system of linear equations A *
  45.      X = B, where A is an N-by-N symmetric matrix stored in packed format and
  46.      X and B are N-by-NRHS matrices. Error bounds on the solution and a
  47.      condition estimate are also provided.
  48.  
  49.  
  50. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  51.      The following steps are performed:
  52.  
  53.      1. If FACT = 'N', the diagonal pivoting method is used to factor A as
  54.            A = U * D * U**T,  if UPLO = 'U', or
  55.            A = L * D * L**T,  if UPLO = 'L',
  56.         where U (or L) is a product of permutation and unit upper (lower)
  57.         triangular matrices and D is symmetric and block diagonal with
  58.         1-by-1 and 2-by-2 diagonal blocks.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      2. If some D(i,i)=0, so that D is exactly singular, then the routine
  75.         returns with INFO = i. Otherwise, the factored form of A is used
  76.         to estimate the condition number of the matrix A.  If the
  77.         reciprocal of the condition number is less than machine precision,
  78.         INFO = N+1 is returned as a warning, but the routine still goes on
  79.         to solve for X and compute error bounds as described below.
  80.  
  81.      3. The system of equations is solved for X using the factored form
  82.         of A.
  83.  
  84.      4. Iterative refinement is applied to improve the computed solution
  85.         matrix and calculate error bounds and backward error estimates
  86.         for it.
  87.  
  88.  
  89. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  90.      FACT    (input) CHARACTER*1
  91.              Specifies whether or not the factored form of A has been supplied
  92.              on entry.  = 'F':  On entry, AFP and IPIV contain the factored
  93.              form of A.  AP, AFP and IPIV will not be modified.  = 'N':  The
  94.              matrix A will be copied to AFP and factored.
  95.  
  96.      UPLO    (input) CHARACTER*1
  97.              = 'U':  Upper triangle of A is stored;
  98.              = 'L':  Lower triangle of A is stored.
  99.  
  100.      N       (input) INTEGER
  101.              The number of linear equations, i.e., the order of the matrix A.
  102.              N >= 0.
  103.  
  104.      NRHS    (input) INTEGER
  105.              The number of right hand sides, i.e., the number of columns of
  106.              the matrices B and X.  NRHS >= 0.
  107.  
  108.      AP      (input) REAL array, dimension (N*(N+1)/2)
  109.              The upper or lower triangle of the symmetric matrix A, packed
  110.              columnwise in a linear array.  The j-th column of A is stored in
  111.              the array AP as follows:  if UPLO = 'U', AP(i + (j-1)*j/2) =
  112.              A(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) =
  113.              A(i,j) for j<=i<=n.  See below for further details.
  114.  
  115.      AFP     (input or output) REAL array, dimension
  116.              (N*(N+1)/2) If FACT = 'F', then AFP is an input argument and on
  117.              entry contains the block diagonal matrix D and the multipliers
  118.              used to obtain the factor U or L from the factorization A =
  119.              U*D*U**T or A = L*D*L**T as computed by SSPTRF, stored as a
  120.              packed triangular matrix in the same storage format as A.
  121.  
  122.              If FACT = 'N', then AFP is an output argument and on exit
  123.              contains the block diagonal matrix D and the multipliers used to
  124.              obtain the factor U or L from the factorization A = U*D*U**T or A
  125.              = L*D*L**T as computed by SSPTRF, stored as a packed triangular
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              matrix in the same storage format as A.
  141.  
  142.      IPIV    (input or output) INTEGER array, dimension (N)
  143.              If FACT = 'F', then IPIV is an input argument and on entry
  144.              contains details of the interchanges and the block structure of
  145.              D, as determined by SSPTRF.  If IPIV(k) > 0, then rows and
  146.              columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1
  147.              diagonal block.  If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then
  148.              rows and columns k-1 and -IPIV(k) were interchanged and D(k-
  149.              1:k,k-1:k) is a 2-by-2 diagonal block.  If UPLO = 'L' and IPIV(k)
  150.              = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were
  151.              interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
  152.  
  153.              If FACT = 'N', then IPIV is an output argument and on exit
  154.              contains details of the interchanges and the block structure of
  155.              D, as determined by SSPTRF.
  156.  
  157.      B       (input) REAL array, dimension (LDB,NRHS)
  158.              The N-by-NRHS right hand side matrix B.
  159.  
  160.      LDB     (input) INTEGER
  161.              The leading dimension of the array B.  LDB >= max(1,N).
  162.  
  163.      X       (output) REAL array, dimension (LDX,NRHS)
  164.              If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X.
  165.  
  166.      LDX     (input) INTEGER
  167.              The leading dimension of the array X.  LDX >= max(1,N).
  168.  
  169.      RCOND   (output) REAL
  170.              The estimate of the reciprocal condition number of the matrix A.
  171.              If RCOND is less than the machine precision (in particular, if
  172.              RCOND = 0), the matrix is singular to working precision.  This
  173.              condition is indicated by a return code of INFO > 0.
  174.  
  175.      FERR    (output) REAL array, dimension (NRHS)
  176.              The estimated forward error bound for each solution vector X(j)
  177.              (the j-th column of the solution matrix X).  If XTRUE is the true
  178.              solution corresponding to X(j), FERR(j) is an estimated upper
  179.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  180.              divided by the magnitude of the largest element in X(j).  The
  181.              estimate is as reliable as the estimate for RCOND, and is almost
  182.              always a slight overestimate of the true error.
  183.  
  184.      BERR    (output) REAL array, dimension (NRHS)
  185.              The componentwise relative backward error of each solution vector
  186.              X(j) (i.e., the smallest relative change in any element of A or B
  187.              that makes X(j) an exact solution).
  188.  
  189.      WORK    (workspace) REAL array, dimension (3*N)
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSSSSSPPPPSSSSVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      IWORK   (workspace) INTEGER array, dimension (N)
  207.  
  208.      INFO    (output) INTEGER
  209.              = 0: successful exit
  210.              < 0: if INFO = -i, the i-th argument had an illegal value
  211.              > 0:  if INFO = i, and i is
  212.              <= N:  D(i,i) is exactly zero.  The factorization has been
  213.              completed but the factor D is exactly singular, so the solution
  214.              and error bounds could not be computed. RCOND = 0 is returned.  =
  215.              N+1: D is nonsingular, but RCOND is less than machine precision,
  216.              meaning that the matrix is singular to working precision.
  217.              Nevertheless, the solution and error bounds are computed because
  218.              there are a number of situations where the computed solution can
  219.              be more accurate than the value of RCOND would suggest.
  220.  
  221. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  222.      The packed storage scheme is illustrated by the following example when N
  223.      = 4, UPLO = 'U':
  224.  
  225.      Two-dimensional storage of the symmetric matrix A:
  226.  
  227.         a11 a12 a13 a14
  228.             a22 a23 a24
  229.                 a33 a34     (aij = aji)
  230.                     a44
  231.  
  232.      Packed storage of the upper triangle of A:
  233.  
  234.      AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]
  235.  
  236.  
  237. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  238.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  239.  
  240.      This man page is available only online.
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.